fix: lazy engine loading, enriched errors, and switchProject tool #123

SimplyLiz · 2026-01-27T17:55:19Z

Summary

MCP server now responds to initialize handshake in ~0.6s instead of 43+ seconds
Engine (SCIP index) is loaded lazily on first tool call, not during startup
Improved ckb setup UX for Claude Code, Grok, and VS Code configuration
Not-found errors now include repo context when the client doesn't support roots/list
New switchProject tool lets AI agents self-correct repo mismatches at runtime
Fixed pagination: all core tools now visible on page 1 (Cursor doesn't request subsequent pages)

Problem

The MCP server was loading the entire SCIP index synchronously before responding to the initialize handshake. For large codebases (e.g., 48MB index), this took 43+ seconds, causing Claude Code's health check to timeout and report "Failed to connect".

Additionally, when a client like Cursor doesn't support roots/list, CKB can't auto-switch to the correct project. Tool errors like SYMBOL_NOT_FOUND gave no indication that the index might be for a different repo, causing AI agents to hallucinate explanations instead of understanding the mismatch. Even with enriched errors hinting at the mismatch, agents had no way to fix it — they could only tell the user to restart.

Changes

`switchProject` Tool (`internal/mcp/server.go`, `internal/mcp/tool_impls_compound.go`, `internal/mcp/tools.go`)

Add switchProject() method that accepts a filesystem path and switches the active engine
Validates path exists, finds git root, checks .ckb/ is initialized
Closes old engine, creates new one via createEngineForRoot()
Works in all modes: single-engine, lazy, multi-repo
Added to core preset (available in all presets)
Unlike switchRepo, does not require pre-registration — accepts any path

Enriched Error Hints (`internal/mcp/server.go`)

enrichNotFoundError() now suggests switchProject instead of "restart CKB"
Gives AI agents an actionable next step they can take autonomously

Pagination Fix (`internal/mcp/cursor.go`)

Bump DefaultPageSize from 15 to 40
Core preset grew to 20 tools but page 1 only showed 15
Cursor (and other clients) don't request page 2, so 5 tools were invisible
getStatus, switchProject, expandToolset, analyzeImpact, getHotspots were all missing

Lazy Engine Loading (`internal/mcp/server.go`)

Add NewMCPServerLazy() that accepts an engine loader function
Engine is created on first tool call that needs it
MCP handshake completes immediately

Repo-Mismatch Detection (`internal/mcp/server.go`, `internal/mcp/tool_impls_compound.go`)

Add enrichNotFoundError() — when a not-found error occurs and the client didn't provide roots, append the indexed repo path to the error message
Switch compound tools from s.engine() to s.GetEngine() to prevent nil panics with lazy loading
Applies to explore, understand, prepareChange, and batchSearch tools

MCP Command (`cmd/ckb/mcp.go`)

Use lazy loading path for all scenarios
Remove tautological nil check flagged by linter
Temporarily disable multi-repo mode (TODO: add lazy support)

Setup Command (`cmd/ckb/setup.go`)

Detect if CKB is already configured correctly (no action needed)
Warn when configured path differs from current binary
Show note when switching between npx and local binary
Automatically update config instead of failing with "already exists"
Grok global setup: Add getGrokMcpConfig() to read existing config; skip when already configured
VS Code global setup: Add getVSCodeGlobalMcpConfig() to read existing config; skip when already configured

Test plan

go build ./cmd/ckb — compiles
go test ./internal/mcp/... — all tests pass (updated for 20 core / 88 full tools)
tools/list returns all 20 core tools on page 1
switchProject and getStatus visible in tool list
MCP handshake completes in <1s (was 43s)
Not-found errors suggest switchProject instead of "restart CKB"
Manual test: start MCP from wrong CWD → error hints at mismatch → switchProject fixes it
ckb setup deduplication works for Claude Code, Grok, VS Code
All existing tests pass

🤖 Generated with Claude Code

github-actions · 2026-01-27T17:57:25Z

🟡 Change Impact Analysis

Metric	Value
Risk Level	MEDIUM 🟡
Files Changed	9
Symbols Changed	259
Directly Affected	1
Transitively Affected	146

Blast Radius: 0 modules, 1 files, 147 unique callers

📝 Changed Symbols (259)

Symbol	File	Type	Confidence
`DefaultPageSize`	`internal/mcp/cursor.go`	modified	100%
`EngineLoader`	`internal/mcp/server.go`	modified	100%
`MCPServer#engineErr`	`internal/mcp/server.go`	modified	100%
`MCPServer#engineLoader`	`internal/mcp/server.go`	modified	100%
`MCPServer#engineOnce`	`internal/mcp/server.go`	modified	100%
`MCPServer#enrichNotFoundError`	`internal/mcp/server.go`	modified	100%
`MCPServer#switchProject`	`internal/mcp/server.go`	modified	100%
`MCPServer#toolSwitchProject`	`internal/mcp/tool_impls_compound.go`	modified	100%
`NewMCPServerLazy`	`cmd/ckb/mcp.go`	modified	100%
`args`	`cmd/ckb/setup.go`	modified	100%
`c`	`cmd/ckb/setup.go`	modified	100%
`ch`	`internal/mcp/tool_impls_compound.go`	modified	100%
`claudeConfigEntry`	`cmd/ckb/setup.go`	modified	100%
`claudeConfigEntry#Args`	`cmd/ckb/setup.go`	modified	100%
`claudeConfigEntry#Command`	`cmd/ckb/setup.go`	modified	100%
…	+244 more

🎯 Affected Downstream (20)

Symbol	Module	Distance	Kind
`unknown`	``	1	direct-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/cmd/ckb`/runMCP().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/BenchmarkToolsListPaginated().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#GetEngine().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#enrichNotFoundError().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#getIndexStaleness().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#getTelemetryStorage().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#handleListToolsRequest().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#streamFindReferences().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#streamSearchSymbols().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolAnalyzeChange().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolAnalyzeCoupling().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolAnalyzeImpact().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolAnnotateModule().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolAuditRisk().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolCancelJob().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolCheckDocStaleness().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolCompareAPI().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/MCPServer#toolDoctor().`	``	2	transitive-caller
`scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f` github.com/SimplyLiz/CodeMCP/internal/mcp`/TestPagination().`	``	2	transitive-caller

Recommendations

⚠️ test: Significant transitive impact (146 symbols). Run comprehensive test suite.
- Action: Run full test suite before merging

⚠️ Index is 0 commit(s) behind HEAD. Results may be incomplete.

_{Generated by CKB}

github-actions · 2026-01-27T17:59:00Z

🔐 Security Audit Results

⚠️ Security gate passed with warnings - 7 issue(s) found (review recommended)

Category	Findings
🔑 Secrets	✅ 0
🛡️ SAST	✅ 0
📦 Dependencies	⚠️ 7
📜 Licenses	⚠️ 144 non-permissive

📦 Dependency Vulnerabilities

Found 7 vulnerability(ies) across 2 scanner(s)

Details

Trivy (4 findings)

CVE-2026-22036 (MEDIUM): undici - undici: Undici: Denial of Service via excessive de...
CVE-2025-54410 (LOW): github.com/docker/docker - github.com/moby/moby: Moby's Firewalld reload remo...
GHSA-vrw8-fxc6-2r93 (MEDIUM): github.com/go-chi/chi/v5 - chi Allows Host Header Injection which Leads to Op...
CVE-2025-47908 (MEDIUM): github.com/rs/cors - github.com/rs/cors: Denial of service via maliciou...

OSV-Scanner (3 findings)

github.com/docker/docker: 2 vulnerabilities
github.com/go-chi/chi/v5: 1 vulnerabilities
github.com/rs/cors: 2 vulnerabilities

📜 License Issues

Found 144 non-permissive license(s)

Details

github.com/BurntSushi/toml: MIT (notice)
github.com/google/uuid: BSD-3-Clause (notice)
github.com/klauspost/compress: Apache-2.0 (notice)
github.com/klauspost/compress: BSD-3-Clause (notice)
github.com/klauspost/compress: MIT (notice)
github.com/pelletier/go-toml/v2: MIT (notice)
github.com/smacker/go-tree-sitter: MIT (notice)
github.com/sourcegraph/go-diff: MIT (notice)
github.com/sourcegraph/scip: Apache-2.0 (notice)
github.com/spf13/cobra: Apache-2.0 (notice)
... and 134 more

_{Generated by CKB Security Audit | View Details | Security Tab}

codecov · 2026-01-27T18:00:30Z

Codecov Report

❌ Patch coverage is 11.26280% with 260 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cmd/ckb/setup.go	0.0%	161 Missing ⚠️
internal/mcp/server.go	8.1%	64 Missing and 4 partials ⚠️
internal/mcp/tool_impls_compound.go	34.2%	20 Missing and 5 partials ⚠️
cmd/ckb/mcp.go	0.0%	6 Missing ⚠️

❌ Your patch status has failed because the patch coverage (11.2%) is below the target coverage (30.0%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff            @@
##           develop    #123     +/-   ##
=========================================
- Coverage     45.1%   44.9%   -0.2%     
=========================================
  Files          350     350             
  Lines        59773   60028    +255     
=========================================
+ Hits         26978   27004     +26     
- Misses       30970   31188    +218     
- Partials      1825    1836     +11

Flag	Coverage Δ
unit	`44.9% <11.2%> (-0.2%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

📢 Thoughts on this report? Let us know!

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-01-27T18:02:15Z

CKB Analysis

🎯 259 changed → 146 affected · 🔥 6 hotspots · 📊 5 complex · 💣 1 blast · 📚 143 stale

Risk factors: Moderate churn: 592 lines changed • Touches 6 hotspot(s)

Metric	Value
Impact Analysis	259 symbols → 146 affected	🟡
Doc Coverage	9.090909090909092%	⚠️
Complexity	5 violations	⚠️
Coupling	0 gaps	✅
Blast Radius	0 modules, 1 files	✅
Index	indexed (8s)	💾

🎯 Change Impact Analysis · 🟡 MEDIUM · 259 changed → 20 affected

Metric	Value
Symbols Changed	259
Directly Affected	1
Transitively Affected	146
Modules in Blast Radius	0
Files in Blast Radius	1

Symbols changed in this PR:

DefaultPageSize [modified] (100%) — internal/mcp/cursor.go
EngineLoader [modified] (100%) — internal/mcp/server.go
MCPServer#engineErr [modified] (100%) — internal/mcp/server.go
MCPServer#engineLoader [modified] (100%) — internal/mcp/server.go
MCPServer#engineOnce [modified] (100%) — internal/mcp/server.go
MCPServer#enrichNotFoundError [modified] (100%) — internal/mcp/server.go
MCPServer#switchProject [modified] (100%) — internal/mcp/server.go
MCPServer#toolSwitchProject [modified] (100%) — internal/mcp/tool_impls_compound.go
NewMCPServerLazy [modified] (100%) — cmd/ckb/mcp.go
args [modified] (100%) — cmd/ckb/setup.go
… and 249 more

Downstream symbols affected:
Direct callers (1):

unknown
Transitive callers (19):
scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f github.com/SimplyLiz/CodeMCP/cmd/ckb/runMCP(). (depth 2)
scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f github.com/SimplyLiz/CodeMCP/internal/mcp/BenchmarkToolsListPaginated(). (depth 2)
scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f github.com/SimplyLiz/CodeMCP/internal/mcp/MCPServer#GetEngine(). (depth 2)
scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f github.com/SimplyLiz/CodeMCP/internal/mcp/MCPServer#enrichNotFoundError(). (depth 2)
scip-go gomod github.com/SimplyLiz/CodeMCP 1bc04aec837f github.com/SimplyLiz/CodeMCP/internal/mcp/MCPServer#getIndexStaleness(). (depth 2)
… and 14 more transitive callers

Recommendations:

⚠️ Significant transitive impact (146 symbols). Run comprehensive test suite.
- Action: Run full test suite before merging

⚠️ Index is undefined commit(s) behind HEAD. Results may be incomplete. Run ckb index to refresh.

💣 Blast radius · 0 symbols · 1 tests · 0 consumers

Tests that may break:

internal/mcp/presets_test.go

🔥 Hotspots · 6 volatile files

File	Churn Score
`cmd/ckb/mcp.go`	11.08
`cmd/ckb/setup.go`	10.30
`internal/mcp/presets.go`	7.78
`internal/mcp/server.go`	11.83
`internal/mcp/tool_impls_compound.go`	8.89
`internal/mcp/tools.go`	11.23

📦 Modules · 1 at risk

	Module	Files
🟡	`internal/mcp`	6

📊 Complexity · 5 violations

File	Cyclomatic	Cognitive
`cmd/ckb/mcp.go`	⚠️ 28	⚠️ 65
`cmd/ckb/setup.go`	⚠️ 27	⚠️ 52
`internal/mcp/presets_test.go`	⚠️ 21	⚠️ 35
`internal/mcp/server.go`	12	⚠️ 22
`internal/mcp/tool_impls_compound.go`	14	⚠️ 25

💡 Quick wins · 10 suggestions

🟡 Add tests → internal/query/engine_test.go
🟡 Add tests → internal/incremental/store_test.go
🟡 Add tests → internal/api/index_processor.go
🟡 Add tests → internal/backends/git/diff.go
🟡 Add tests → internal/query/doctor.go
🟢 Assign backup owner → internal/query/engine_test.go
🟢 Assign backup owner → internal/incremental/store_test.go
🟢 Assign backup owner → internal/api/index_processor.go

📚 Stale docs · 143 broken references

docs/CONTRIBUTING.md:108 → errors.New
docs/CONTRIBUTING.md:108 → errors.SYMBOL_NOT_FOUND
docs/CONTRIBUTING.md:111 → errors.Wrap
docs/backlog/index-refresh-improvements.md:36 → watcher.Add
docs/backlog/index-refresh-improvements.md:36 → filepath.Join
docs/backlog/index-refresh-improvements.md:97 → time.Second
docs/featureplans/change-impact-analysis-checklist.md:208 → coverage.out
docs/featureplans/change-impact-analysis-checklist.md:214 → lcov.info
docs/featureplans/change-impact-analysis-checklist.md:309 → coverage.out
docs/featureplans/change-impact-analysis.md:448 → scip.SCIPIndex
docs/featureplans/change-impact-analysis.md:478 → context.Context
docs/featureplans/change-impact-analysis.md:669 → coverage.out
docs/ideas.md:16 → provenance.backends
docs/ideas.md:21 → queryPolicy.coalesceWindowMs
docs/ideas.md:302 → confidence.factors

_{Generated by CKB · Run details}

MCP server was taking 43+ seconds to respond to initialize handshake because it loaded the entire SCIP index synchronously before starting. Changes: - Add NewMCPServerLazy() that accepts an engine loader function - Engine is now loaded on first tool call, not during startup - MCP handshake completes in ~0.6s instead of 43s - Temporarily disable multi-repo mode to use lazy path everywhere Also improves `ckb setup` for Claude Code: - Detect if CKB is already configured correctly (no action needed) - Warn when configured path differs from current binary - Show note when switching between npx and local binary - Automatically update config instead of failing with "already exists" Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…ots support When an MCP client (e.g. Cursor) doesn't support roots/list, tool errors like SYMBOL_NOT_FOUND give no indication that the index might be for a different project. This adds repo path context to those errors so the AI agent can understand the mismatch. Also switches compound tools to GetEngine() to prevent nil panics with lazy loading. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

configureGrokGlobal and configureVSCodeGlobal now check for existing config before calling their respective CLIs, matching the pattern already used by configureClaudeCodeGlobal via claudeMcpAdd. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Cursor (and other MCP clients without roots/list support) doesn't pass the workspace directory to MCP servers, so CKB falls back to the wrong project. The new switchProject tool lets AI agents self-correct by switching to the correct repo path at runtime. Changes: - Add switchProject() method and toolSwitchProject handler - Register tool in core preset (available in all presets) - Update enrichNotFoundError() to suggest switchProject instead of restart - Bump DefaultPageSize from 15 to 40 so all core tools appear on page 1 (Cursor doesn't request subsequent pages) - Update tests for new tool count (core: 20, full: 88) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

SimplyLiz force-pushed the feat/setup-improvements branch from 9781ed9 to 24c7f34 Compare January 30, 2026 11:23

SimplyLiz force-pushed the feat/setup-improvements branch from db8fa49 to 3d702d1 Compare January 30, 2026 11:41

SimplyLiz and others added 2 commits January 30, 2026 12:48

SimplyLiz changed the title ~~fix: lazy engine loading for fast MCP startup~~ fix: lazy engine loading, enriched errors, and switchProject tool Jan 31, 2026

fix: resolve govet shadow warnings in switchProject

3033be5

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

SimplyLiz merged commit b720cb1 into develop Jan 31, 2026
20 of 22 checks passed

SimplyLiz deleted the feat/setup-improvements branch January 31, 2026 10:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: lazy engine loading, enriched errors, and switchProject tool #123

fix: lazy engine loading, enriched errors, and switchProject tool #123

Uh oh!

SimplyLiz commented Jan 27, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 27, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 27, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 27, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

fix: lazy engine loading, enriched errors, and switchProject tool #123

fix: lazy engine loading, enriched errors, and switchProject tool #123

Uh oh!

Conversation

SimplyLiz commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Changes

switchProject Tool (internal/mcp/server.go, internal/mcp/tool_impls_compound.go, internal/mcp/tools.go)

Enriched Error Hints (internal/mcp/server.go)

Pagination Fix (internal/mcp/cursor.go)

Lazy Engine Loading (internal/mcp/server.go)

Repo-Mismatch Detection (internal/mcp/server.go, internal/mcp/tool_impls_compound.go)

MCP Command (cmd/ckb/mcp.go)

Setup Command (cmd/ckb/setup.go)

Test plan

Uh oh!

github-actions bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Change Impact Analysis

Recommendations

Uh oh!

github-actions bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔐 Security Audit Results

📦 Dependency Vulnerabilities

📜 License Issues

Uh oh!

codecov bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CKB Analysis

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SimplyLiz commented Jan 27, 2026 •

edited

Loading

`switchProject` Tool (`internal/mcp/server.go`, `internal/mcp/tool_impls_compound.go`, `internal/mcp/tools.go`)

Enriched Error Hints (`internal/mcp/server.go`)

Pagination Fix (`internal/mcp/cursor.go`)

Lazy Engine Loading (`internal/mcp/server.go`)

Repo-Mismatch Detection (`internal/mcp/server.go`, `internal/mcp/tool_impls_compound.go`)

MCP Command (`cmd/ckb/mcp.go`)

Setup Command (`cmd/ckb/setup.go`)

github-actions bot commented Jan 27, 2026 •

edited

Loading

github-actions bot commented Jan 27, 2026 •

edited

Loading

codecov bot commented Jan 27, 2026 •

edited

Loading

github-actions bot commented Jan 27, 2026 •

edited

Loading